---
title: Guidelines
redirect_from:
  - /components/badge/
---

<ReactExample exampleId="BadgeList-default" />

## When to use

- To display several details about a single idea like a transfer at an airport.
- To use common visual cues (icons and colors) to help users scan the details.

## When not to use

- If the users can take an action---use the right [action component](/design-patterns/action-components/).
- When the information isn't about only one thing---use a [list](/components/structure/list/).
- With a single, simple piece of information---use a [badge](/components/information/badge/).
- If there are choices the user must make---use [list choices](/components/input/listchoice/).

## Component status

<ComponentStatus component="BadgeList" />

## Content structure

![BadgeListItem: includes one item in the list; label: works best when short; icon: supports the label.](fileId:4QJZqvBvRrLu6t9mwObCkA;nodeId:1418%3A0)

## Content

### Display short, static info

The items in the list should all be static information, **not** actionable.

If you have extra information to display, include it with [progressive disclosure](/design-patterns/progressive-disclosure/).
Use a simple interaction, such as a [tooltip](/components/overlay/tooltip/)
or a secondary [text link](/components/action/textlink/) to open contextual help.

When doing so, make sure it's clear that the interaction is there.

<ReactExample minHeight="200" exampleId="BadgeList-disclosure" />

### Support with icons

With a small space to convey a message and possibly several items to show,
visual cues can help users scan and understand the idea more quickly.
Use icons to display more information in a smaller space,
such as what form of transport is included.

Make sure that any information you include in the icon is [accessible](/foundation/accessibility/),
either in the text around it or as a label to the icon.

## Look & feel

### List item types

There are five types for the badge list items.

<ReactExample minHeight="200" exampleId="BadgeList-types" />

#### Neutral items

Neutral badge list items present information without adding any emotion.
They're useful when the information isn't so important to the user's main flow.

#### Info items

Informational badge list items help to highlight some information as particularly important.
They draw attention to the item without making it seem positive or negative.

#### Success items

Success badge list items help to highlight a desirable detail.
Use them for potentially attractive features (such as a guaranteed transfer).

#### Warning items

Warning badge list items highlight information that users need to be aware of to avoid problems.
They're associated with negative emotions
so only use them occasionally to stop potential problems before they happen.

#### Critical items

Critical badge list items call attention to problems require attention from users.
For example, as a reason a specific choice can't be made,
or to highlight that they might not be protected by a service (like a guarantee).
These badges create feelings of stress so only use them for issues where they're truly necessary.
